Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Convert command-line tools to use GNU-style long options #541

Merged
merged 18 commits into from
Oct 28, 2024
Merged

Conversation

walbourn
Copy link
Member

@walbourn walbourn commented Oct 24, 2024

Embraces the -so vs. --long-option GNU-like pattern for the command-line tools.

This also adds -o=value which is the GNU standard and the tool already supported -o:value or -o value.

Also fixed some bugs with texdiag's output filename extension and added support for -o <path> to the dumpdds command.

This is a hybrid of the Windows style and GNU-like pattern. For example, you can't combine single-characters together such as -yl with this tool like you can with GNU-style argument syntax. Not all multi-character options use -- which would be the GNU standard.

The tool already supports the -- escape so you can start filenames with / or -

@walbourn walbourn added the tools Applies to texconv, texdiag, texassemble, etc. label Oct 24, 2024
@walbourn walbourn self-assigned this Oct 24, 2024
@walbourn
Copy link
Member Author

walbourn commented Oct 24, 2024

The help output for texconv now reads:

Microsoft (R) DirectX Texture Converter [DirectXTex] Version 205 (library)
Copyright (C) Microsoft Corp.
*** Debug build ***

Usage: texconv <options> [--] <files>

   -r                  wildcard filename search is recursive
     -r:flatten        flatten the directory structure (default)
     -r:keep           keep the directory structure
   -flist <filename>, --file-list <filename>
                       use text file with a list of input files (one per line)

   -w <n>, --width <n>                     width for output
   -h <n>, --height <n>                    height for output
   -m <n>, --mip-levels <n>                miplevels for output
   -f <format>, --format <format>          pixel format for output

   -if <filter>, --image-filter <filter>   image filtering
   -srgb{i|o}, --srgb-in, --srgb-out       sRGB {input, output}

   -px <string>, --prefix <string>         name prefix
   -sx <string>, --suffix <string>         name suffix
   -o <directory>                          output directory
   -l, --to-lowercase                      force output filename to lower case
   -y, --overwrite                         overwrite existing output file (if any)
   -ft <filetype>, --file-type <filetype>  output file type

   -hflip, --horizontal-flip               horizonal flip of source image
   -vflip, --vertical-flip                 vertical flip of source image

   -sepalpha, --separate-alpha   resize/generate mips alpha channel separately from color channels
   --keep-coverage <ref>         Preserve alpha coverage in mips for alpha test ref

   -nowic                             Force non-WIC filtering
   -wrap, -mirror                     texture addressing mode (wrap, mirror, or clamp)
   -pmalpha, --premultiplied-alpha    convert final texture to use premultiplied alpha
   -alpha                             convert premultiplied alpha to straight alpha
   -at <threshold>, --alpha-threshold <threshold>
                                      Alpha threshold used for BC1, RGBA5551, and WIC
                                      (defaults to 0.5)

   -fl <feature-level>, --feature-level <feature-level>
                       Set maximum feature level target (defaults to 11.0)
   -pow2, --fit-power-of-2
                       resize to fit a power-of-2, respecting aspect ratio

   -nmap <options>, --normal-map <options>
                       converts height-map to normal-map
                       options must be one or more of
                          r, g, b, a, l, m, u, v, i, o
   -nmapamp <weight>, --normal-map-amplitude <weight>
                       normal map amplitude (defaults to 1.0)

                                  (DDS input only)
   -tu, --typeless-unorm          TYPELESS format is treated as UNORM
   -tf, --typeless-float          TYPELESS format is treated as FLOAT
   -dword, --dword-alignment      Use DWORD instead of BYTE alignment
   --bad-tails                    Fix for older DXTn with bad mipchain tails
   --permissive                   Allow some DX9 variants with unusual header values
   --ignore-mips                  Reads just the top-level mip which reads some invalid files
   --fix-bc-4x4                   Fix for odd-sized BC files that Direct3D can't load
   -xlum, --expand-luminance      Expand legacy L8, L16, and A8P8 formats

                       (DDS output only)
   -dx10               Force use of 'DX10' extended header
   -dx9                Force use of legacy DX9 header

                       (TGA input only)
   --tga-zero-alpha    Allow all zero alpha channel files to be loaded 'as is'

                       (TGA output only)
   -tga20              Write file including TGA 2.0 extension area

                       (BMP, PNG, JPG, TIF, WDP output only)
   -wicq <quality>, --wic-quality <quality>
                       When writing images with WIC use quality (0.0 to 1.0)
   --wic-lossless      When writing images with WIC use lossless mode
   --wic-multiframe    When writing images with WIC encode multiframe images

   -nologo             suppress copyright message
   --timing            display elapsed processing time

   --single-proc       Do not use multi-threaded compression
   -gpu <adapter>      Select GPU for DirectCompute-based codecs (0 is default)
   -nogpu              Do not use DirectCompute-based codecs

   -bc <options>, --block-compress <options>
                       Sets options for BC compression
                       options must be one or more of
                          d, u, q, x
   -aw <weight>, --alpha-weight <weight>
                       BC7 GPU compressor weighting for alpha error metric
                       (defaults to 1.0)

   -c <hex-RGB>, --color-key <hex-RGB>    colorkey (a.k.a. chromakey) transparency
   --rotate-color <rot>                   rotates color primaries and/or applies a curve

   -nits <value>, --paper-white-nits <value>
                       paper-white value in nits to use for HDR10 (def: 200.0)
   --tonemap           Apply a tonemap operator based on maximum luminance
   --x2-bias           Enable *2 - 1 conversion cases for unorm/pos-only-float
   --invert-y          Invert Y (i.e. green) channel values
   --reconstruct-z     Rebuild Z (blue) channel assuming X/Y are normals
   --swizzle <rgba>    Swizzle image channels using HLSL-style mask

   '-- ' is needed if any input filepath starts with the '-' or '/' character

   <format>: R32G32B32A32_FLOAT R32G32B32A32_UINT R32G32B32A32_SINT 
      R32G32B32_FLOAT R32G32B32_UINT R32G32B32_SINT R16G16B16A16_FLOAT 
      R16G16B16A16_UNORM R16G16B16A16_UINT R16G16B16A16_SNORM 
      R16G16B16A16_SINT R32G32_FLOAT R32G32_UINT R32G32_SINT 
      R10G10B10A2_UNORM R10G10B10A2_UINT R11G11B10_FLOAT R8G8B8A8_UNORM 
      R8G8B8A8_UNORM_SRGB R8G8B8A8_UINT R8G8B8A8_SNORM R8G8B8A8_SINT 
      R16G16_FLOAT R16G16_UNORM R16G16_UINT R16G16_SNORM R16G16_SINT 
      R32_FLOAT R32_UINT R32_SINT R8G8_UNORM R8G8_UINT R8G8_SNORM 
      R8G8_SINT R16_FLOAT R16_UNORM R16_UINT R16_SNORM R16_SINT 
      R8_UNORM R8_UINT R8_SNORM R8_SINT A8_UNORM R9G9B9E5_SHAREDEXP 
      R8G8_B8G8_UNORM G8R8_G8B8_UNORM BC1_UNORM BC1_UNORM_SRGB BC2_UNORM 
      BC2_UNORM_SRGB BC3_UNORM BC3_UNORM_SRGB BC4_UNORM BC4_SNORM 
      BC5_UNORM BC5_SNORM B5G6R5_UNORM B5G5R5A1_UNORM B8G8R8A8_UNORM 
      B8G8R8X8_UNORM R10G10B10_XR_BIAS_A2_UNORM B8G8R8A8_UNORM_SRGB 
      B8G8R8X8_UNORM_SRGB BC6H_UF16 BC6H_SF16 BC7_UNORM BC7_UNORM_SRGB 
      AYUV Y410 Y416 YUY2 Y210 Y216 B4G4R4A4_UNORM A4B4G4R4_UNORM 
      DXT1 DXT2 DXT3 DXT4 DXT5 RGBA BGRA BGR FP16 FP32 BPTC 
      BPTC_FLOAT 
      BC3n DXT5nm RXGB 

   <filter>: POINT LINEAR CUBIC FANT BOX TRIANGLE POINT_DITHER 
      LINEAR_DITHER CUBIC_DITHER FANT_DITHER BOX_DITHER TRIANGLE_DITHER 
      POINT_DITHER_DIFFUSION LINEAR_DITHER_DIFFUSION CUBIC_DITHER_DIFFUSION 
      FANT_DITHER_DIFFUSION BOX_DITHER_DIFFUSION TRIANGLE_DITHER_DIFFUSION 

   <rot>: 709to2020 2020to709 709toHDR10 HDR10to709 P3D65to2020 
      P3D65toHDR10 709toP3D65 P3D65to709 

   <filetype>: bmp jpg jpeg png dds ddx tga hdr tif tiff wdp hdp 
      jxr ppm pfm heic heif 

   <feature-level>: 9.1 9.2 9.3 10.0 10.1 11.0 11.1 12.0 12.1 12.2 

   <adapter>:
      0: VID:10DE, PID:2488 - NVIDIA GeForce RTX 3070
      1: VID:1414, PID:008C - Microsoft Basic Render Driver

All the existing older switches are still accepted, but are deprecated per this table:

Old switch New switch
-badtails --bad-tails
-fixbc4x4 --fix-bc-4x4
-ignoremips --ignore-mips
-inverty --invert-y
-keepcoverage --keep-coverage
-permissive --permissive
-reconstructz --reconstruct-z
-rotatecolor --rotate-color
-singleproc --single-proc
-swizzle --swizzle
-tgazeroalpha --tga-zero-alpha
-timing --timing
-tonemap --tonemap
-wiclossless --wic-lossless
-wicmulti --wic-multiframe
-x2bias --x2-bias

@walbourn
Copy link
Member Author

@walbourn
Copy link
Member Author

@scm-xbox @Andrew-Farrier My question is this an improvement or does the fact that it's not strictly GNU Argument syntax make it more confusing than helpful?

@walbourn walbourn changed the title Convert texconv to use GNU-style long options Convert command-line tools to use GNU-style long options Oct 26, 2024
@walbourn
Copy link
Member Author

walbourn commented Oct 26, 2024

The help output for texassemble now reads:

Microsoft (R) DirectX Texture Assembler [DirectXTex] Version 205 (library)
Copyright (C) Microsoft Corp.
*** Debug build ***

Usage: texassemble <command> <options> [--] <files>

COMMANDS
   cube                create cubemap
   volume              create volume map
   array               create texture array
   cubearray           create cubemap array
   h-cross or v-cross  create a cross image from a cubemap
   v-cross-fnz         create a cross image flipping the -Z face
   h-tee               create a 'T' image from a cubemap
   h-strip or v-strip  create a strip image from a cubemap
   array-strip         create a strip image from a 1D/2D array
   merge               create texture from rgb image and alpha image
   gif                 create array from animated gif
   cube-from-hc        create cubemap from a h-cross image
   cube-from-vc        create cubemap from a v-cross image
   cube-from-vc-fnz    create cubemap from a v-cross image flipping the -Z face
   cube-from-ht        create cubemap from a h-tee image
   cube-from-hs        create cubemap from a h-strip image
   cube-from-vs        create cubemap from a v-strip image

OPTIONS
   -r                  wildcard filename search is recursive
   -flist <filename>, --file-list <filename>
                       use text file with a list of input files (one per line)

   -w <n>, --width <n>                     width for output
   -h <n>, --height <n>                    height for output
   -f <format>, --format <format>          pixel format for output

   -if <filter>, --image-filter <filter>   image filtering
   -srgb{i|o}, --srgb-in, --srgb-out       sRGB {input, output}

   -o <filename>                           output filename
   -l, --to-lowercase                      force output filename to lower case
   -y, --overwrite                         overwrite existing output file (if any)

   -sepalpha, --separate-alpha   resize/generate mips alpha channel separately from color channels

   -nowic              Force non-WIC filtering
   -wrap, -mirror      texture addressing mode (wrap, mirror, or clamp)
   -alpha              convert premultiplied alpha to straight alpha
   -dx10               Force use of 'DX10' extended header
   -nologo             suppress copyright message

   -fl <feature-level>, --feature-level <feature-level>
                       Set maximum feature level target (defaults to 11.0)

   -tonemap            Apply a tonemap operator based on maximum luminance

                       (gif only)
   --gif-bg-color      Use background color instead of transparency

                       (merge only)
   --swizzle <rgba>    Select channels for merge (defaults to rgbB)

                       (cube, volume, array, cubearray, merge only)
   --strip-mips        Use only base image from input dds files

   '-- ' is needed if any input filepath starts with the '-' or '/' character

   <format>: R32G32B32A32_FLOAT R32G32B32A32_UINT R32G32B32A32_SINT 
      R32G32B32_FLOAT R32G32B32_UINT R32G32B32_SINT R16G16B16A16_FLOAT 
      R16G16B16A16_UNORM R16G16B16A16_UINT R16G16B16A16_SNORM 
      R16G16B16A16_SINT R32G32_FLOAT R32G32_UINT R32G32_SINT 
      R10G10B10A2_UNORM R10G10B10A2_UINT R11G11B10_FLOAT R8G8B8A8_UNORM 
      R8G8B8A8_UNORM_SRGB R8G8B8A8_UINT R8G8B8A8_SNORM R8G8B8A8_SINT 
      R16G16_FLOAT R16G16_UNORM R16G16_UINT R16G16_SNORM R16G16_SINT 
      R32_FLOAT R32_UINT R32_SINT R8G8_UNORM R8G8_UINT R8G8_SNORM 
      R8G8_SINT R16_FLOAT R16_UNORM R16_UINT R16_SNORM R16_SINT 
      R8_UNORM R8_UINT R8_SNORM R8_SINT A8_UNORM R9G9B9E5_SHAREDEXP 
      R8G8_B8G8_UNORM G8R8_G8B8_UNORM B5G6R5_UNORM B5G5R5A1_UNORM 
      B8G8R8A8_UNORM B8G8R8X8_UNORM R10G10B10_XR_BIAS_A2_UNORM 
      B8G8R8A8_UNORM_SRGB B8G8R8X8_UNORM_SRGB AYUV Y410 Y416 YUY2 Y210 
      Y216 B4G4R4A4_UNORM A4B4G4R4_UNORM 
      RGBA BGRA BGR FP16 FP32 

   <filter>: POINT LINEAR CUBIC FANT BOX TRIANGLE POINT_DITHER 
      LINEAR_DITHER CUBIC_DITHER FANT_DITHER BOX_DITHER TRIANGLE_DITHER 
      POINT_DITHER_DIFFUSION LINEAR_DITHER_DIFFUSION CUBIC_DITHER_DIFFUSION 
      FANT_DITHER_DIFFUSION BOX_DITHER_DIFFUSION TRIANGLE_DITHER_DIFFUSION 

   <feature-level>: 9.1 9.2 9.3 10.0 10.1 11.0 11.1 12.0 12.1 12.2 

All the existing older switches are still accepted, but are deprecated per this table:

Old switch New switch
-tonemap --tonemap
-bgcolor --gif-bg-color
-swizzle --swizzle
-stripmips --strip-mips

@walbourn
Copy link
Member Author

The help output for texdiag now reads:

Microsoft (R) DirectX Texture Diagnostic Tool [DirectXTex] Version 205 (library)
Copyright (C) Microsoft Corp.
*** Debug build ***

Usage: texdiag <command> <options> [--] <files>

COMMANDS
   info                Output image metadata
   analyze             Analyze and summarize image information
   compare             Compare two images with MSE error metric
   diff                Generate difference image from two images
   dumpbc              Dump out compressed blocks (DDS BC only)
   dumpdds             Dump out all the images in a complex DDS

OPTIONS
   -r                  wildcard filename search is recursive
   -flist <filename>, --file-list <filename>
                       use text file with a list of input files (one per line)

   -if <filter>, --image-filter <filter>   image filtering

                                  (DDS input only)
   -tu, --typeless-unorm          TYPELESS format is treated as UNORM
   -tf, --typeless-float          TYPELESS format is treated as FLOAT
   -dword, --dword-alignment      Use DWORD instead of BYTE alignment
   --bad-tails                    Fix for older DXTn with bad mipchain tails
   --permissive                   Allow some DX9 variants with unusual header values
   --ignore-mips                  Reads just the top-level mip which reads some invalid files
   -xlum, --expand-luminance      Expand legacy L8, L16, and A8P8 formats

                                  (diff only)
   -f <format>, --format <format> pixel format for output
   -o <filename>                  output filename for diff
   -l, --to-lowercase             force output filename to lower case
   -y, --overwrite                overwrite existing output file (if any)
   -c <hex-RGB>, --diff-color <hex-RGB>
                                  highlight difference color (defaults to off)
   -t <threshold>, --threshold <threshold>
                                  highlight threshold (defaults to 0.25)

                       (dumpbc only)
   --target-x <num>    dump pixels at location x (defaults to all)
   --target-y <num>    dump pixels at location y (defaults to all)

                       (dumpdds only)
   -o <path>           output path for dumpdds
   -ft <filetype>, --file-type <filetype>
                        output file type

   -nologo             suppress copyright message

   '-- ' is needed if any input filepath starts with the '-' or '/' character

   <format>: R32G32B32A32_FLOAT R32G32B32A32_UINT R32G32B32A32_SINT 
      R32G32B32_FLOAT R32G32B32_UINT R32G32B32_SINT R16G16B16A16_FLOAT 
      R16G16B16A16_UNORM R16G16B16A16_UINT R16G16B16A16_SNORM 
      R16G16B16A16_SINT R32G32_FLOAT R32G32_UINT R32G32_SINT 
      R10G10B10A2_UNORM R10G10B10A2_UINT R11G11B10_FLOAT R8G8B8A8_UNORM 
      R8G8B8A8_UNORM_SRGB R8G8B8A8_UINT R8G8B8A8_SNORM R8G8B8A8_SINT 
      R16G16_FLOAT R16G16_UNORM R16G16_UINT R16G16_SNORM R16G16_SINT 
      R32_FLOAT R32_UINT R32_SINT R8G8_UNORM R8G8_UINT R8G8_SNORM 
      R8G8_SINT R16_FLOAT R16_UNORM R16_UINT R16_SNORM R16_SINT 
      R8_UNORM R8_UINT R8_SNORM R8_SINT A8_UNORM R9G9B9E5_SHAREDEXP 
      R8G8_B8G8_UNORM G8R8_G8B8_UNORM B5G6R5_UNORM B5G5R5A1_UNORM 
      B8G8R8A8_UNORM B8G8R8X8_UNORM R10G10B10_XR_BIAS_A2_UNORM 
      B8G8R8A8_UNORM_SRGB B8G8R8X8_UNORM_SRGB AYUV Y410 Y416 YUY2 Y210 
      Y216 B4G4R4A4_UNORM A4B4G4R4_UNORM 
      RGBA BGRA BGR FP16 FP32 

   <filter>: POINT LINEAR CUBIC FANT BOX TRIANGLE POINT_DITHER 
      LINEAR_DITHER CUBIC_DITHER FANT_DITHER BOX_DITHER TRIANGLE_DITHER 
      POINT_DITHER_DIFFUSION LINEAR_DITHER_DIFFUSION CUBIC_DITHER_DIFFUSION 
      FANT_DITHER_DIFFUSION BOX_DITHER_DIFFUSION TRIANGLE_DITHER_DIFFUSION 

   <filetype>: bmp jpg jpeg png tga hdr tif tiff jxr 

All the existing older switches are still accepted, but are deprecated per this table:

Old switch New switch
-badtails --bad-tails
-ignoremips --ignore-mips
-permissive --permissive
-targetx --target-x
-targety --target-y

@walbourn walbourn marked this pull request as ready for review October 26, 2024 01:51
@walbourn walbourn merged commit b81e202 into main Oct 28, 2024
83 checks passed
@walbourn walbourn deleted the gnucommandline branch October 28, 2024 20:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
tools Applies to texconv, texdiag, texassemble, etc.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants